Skip to content

fix: JTBD compliance audit for Secure module - #3159

Merged
gtrivedi88 merged 1 commit into
eclipse-che:mainfrom
gtrivedi88:jtbd-secure-audit
Jul 28, 2026
Merged

fix: JTBD compliance audit for Secure module#3159
gtrivedi88 merged 1 commit into
eclipse-che:mainfrom
gtrivedi88:jtbd-secure-audit

Conversation

@gtrivedi88

@gtrivedi88 gtrivedi88 commented Jul 7, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Align Secure module with downstream JTBD standards and CQA 2.1 editorial quality
  • Fix metadata (descriptions, abstracts, verb consistency), structure (block titles to headings, JTBD sections), and procedures (verification, step verbs, admonition format)
  • Remove unused persona partial, inline cross-module snippet content

Changes

Metadata and abstracts:

  • Fix :description: attributes from gerunds to JTBD titles on all 5 pages
  • Fix title-abstract verb consistency (first verb in title matches first verb in abstract)
  • Fix self-referential abstract in managing-identities-and-authorizations.adoc

Structure (security-best-practices.adoc):

  • Convert 12 . block titles to == headings so sections appear in the page TOC sidebar
  • Add 3 JTBD orientation sections: "What is secure by default", "What you must configure", "What you can optionally harden"
  • Inline 4 cross-module snippet includes with equivalent text
  • Add .Additional resources section with xrefs and external links
  • Fix subsection headings: "Managing extensions" (gerund), "Secrets" (single word), "Authentication" (single word)

Procedures:

  • Remove generic snip_persona-admin.adoc includes from all pages (guide-level callout + prerequisites serve as audience gate)
  • Delete unused partials/snip_persona-admin.adoc
  • Fix cluster-roles example file: gerund title to imperative, add .Verification and .Additional resources, fix "Find out" to "Determine"
  • Fix advanced-authorization: convert [NOTE] to continuation text, add .Verification and .Additional resources
  • Fix GDPR page: hardcoded oc to {orch-cli}, inline admonitions to block format, add .Verification

Zero content loss

Verified via git diff against pre-PR #3134 state (08e76b97^). All procedure steps, code blocks, YAML examples, and technical details preserved. Only titles, abstracts, metadata, and structural formatting changed.

Test plan

  • Antora build passes with 0 errors
  • No new broken xrefs
  • All page TOC sidebars show correct section headings
  • Downstream equivalent already committed and validated (validate-refs 0 errors, Vale 0/0/0)

Made with Cursor

@gtrivedi88
gtrivedi88 requested review from a team, deerskindoll and mkuznyetsov as code owners July 7, 2026 06:48
@gtrivedi88
gtrivedi88 requested a review from azatsarynnyy July 7, 2026 06:48
@github-actions

github-actions Bot commented Jul 7, 2026 •
edited
Loading

Copy link
Copy Markdown

Click here to review and test in web IDE: Contribute

@github-actions

github-actions Bot commented Jul 7, 2026 •
edited
Loading

Copy link
Copy Markdown

🎊 Navigate the preview: https://6a677e3d4cf3156d424c2d6e--eclipse-che-docs-pr.netlify.app 🎊

@gtrivedi88
gtrivedi88 force-pushed the jtbd-secure-audit branch 4 times, most recently from af965a4 to 3dc35fa Compare July 16, 2026 02:12
ibuziuk
ibuziuk reviewed Jul 21, 2026
View reviewed changes
Comment thread modules/secure/pages/security-best-practices.adoc Outdated
@@ -1,51 +1,71 @@
:_content-type: CONCEPT
:description: Security best practices
:description: Protect your deployment

@ibuziuk ibuziuk Jul 21, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
:description: Protect your deployment
:description: Security best practices

@ibuziuk ibuziuk Jul 21, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I prefer having this worded as Security best practices since it was the original request

ibuziuk
ibuziuk approved these changes Jul 21, 2026
View reviewed changes

@ibuziuk ibuziuk left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tolusha please, review as well

tolusha
tolusha reviewed Jul 27, 2026
View reviewed changes
Comment thread modules/secure/pages/configuring-advanced-authorization.adoc Outdated
If `allowUsers` and `allowGroups` are empty, all users are allowed to access {prod-short} except the ones on the `deny` lists.
If `denyUsers` and `denyGroups` are empty, only the users from `allow` lists are allowed to access {prod-short}.
* Log in to the {prod-short} dashboard as a user on the `allowUsers` list and verify access to the dashboard.
* Log in as a user on the `denyUsers` list and verify that {prod-short} returns a `403 Forbidden` response.

@tolusha tolusha Jul 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

User will see the message:

Advanced authorization is enabled. User might not be allowed. Please, contact the administrator.

@gtrivedi88 gtrivedi88 Jul 27, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tolusha Fixed — updated the verification to show the actual message the user sees:

Advanced authorization is enabled. User might not be allowed. Please, contact the administrator.

tolusha
tolusha reviewed Jul 27, 2026
View reviewed changes
Comment thread modules/secure/pages/configuring-advanced-authorization.adoc Outdated
You can determine which users and groups are allowed to access {prod-short}.

include::partial$snip_persona-admin.adoc[]
Restrict {prod-short} access to specific users and groups so that you can enforce access policies and limit the platform to authorized teams.

@tolusha tolusha Jul 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe it is a bit incorrect. Platform (openShift) authorize user anyway, but the product (Che/DevSpaces) allow/deny access

@gtrivedi88 gtrivedi88 Jul 27, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tolusha Good catch. Reworded the abstract to avoid "authorize" — it now reads:

Restrict {prod-short} access to specific users and groups so that you can control which users are allowed or denied access to the platform.

This reflects that Che/DevSpaces allows or denies access, while OpenShift handles the actual authorization.

tolusha
tolusha reviewed Jul 27, 2026
View reviewed changes

@tolusha tolusha left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@gtrivedi88
Pls, have a look at my comments above

@gtrivedi88 @cursoragent
fix: JTBD compliance audit for Secure module
3f05653 
Align upstream Secure module with downstream JTBD standards and
CQA 2.1 editorial quality. Address Secure hierarchy review gaps.

Metadata and abstracts:
- Fix :description: attributes (gerunds -> JTBD titles)
- Fix title-abstract verb consistency on all pages
- Fix self-referential abstract in managing-identities page

Structure (security-best-practices.adoc):
- Convert block titles to == headings (appear in page TOC)
- Add JTBD orientation sections and bridge sentences
- Remove duplicated advancedAuthorization YAML example
- Strengthen thin credentials and trusted-Git subsections
- Rename weak H2s (gateway, air-gapped, IDE extensions, namespace resources)
- Add [role="_additional-resources"] and cross-module xrefs
- Plan-style nav: unlinked job group for access-control procedures

Procedures:
- Remove generic persona snippet includes
- Delete unused partials/snip_persona-admin.adoc
- Fix cluster-roles example: kubectl -> {orch-cli}, Verification, AR
- Fix advanced-authorization and GDPR pages

Zero content loss for procedure steps, RBAC table, and SCC examples.

Co-authored-by: Cursor <cursoragent@cursor.com>
@gtrivedi88
gtrivedi88 merged commit d85bc70 into eclipse-che:main Jul 28, 2026
6 checks passed
gtrivedi88 added a commit to gtrivedi88/che-docs that referenced this pull request Jul 28, 2026
@gtrivedi88 @cursoragent
fix: escape shell variables in cluster-roles source blocks
0adde1c 
The Secure audit PR (eclipse-che#3159) added +attributes to source blocks
that contain shell variables ${USER_ROLES} and ${OPERATOR_NAMESPACE}.
Asciidoctor tried to resolve these as AsciiDoc attributes, causing
"missing attribute" warnings that fail the publication builder.

Escape with backslash so Asciidoctor renders them literally while
still resolving {orch-cli} and {prod-operator}.

Co-authored-by: Cursor <cursoragent@cursor.com>
@gtrivedi88 gtrivedi88 mentioned this pull request Jul 28, 2026
Merged
gtrivedi88 added a commit to gtrivedi88/che-docs that referenced this pull request Jul 28, 2026
@gtrivedi88 @cursoragent
fix: escape shell variables in cluster-roles source blocks
b7f274c 
The Secure audit PR (eclipse-che#3159) added +attributes to source blocks
that contain shell variables ${USER_ROLES} and ${OPERATOR_NAMESPACE}.
Asciidoctor tried to resolve these as AsciiDoc attributes, causing
"missing attribute" warnings that fail the publication builder.

Escape with backslash so Asciidoctor renders them literally while
still resolving {orch-cli} and {prod-operator}.

Co-authored-by: Cursor <cursoragent@cursor.com>
gtrivedi88 added a commit that referenced this pull request Jul 28, 2026
@gtrivedi88 @cursoragent
fix: escape shell variables in cluster-roles source blocks (#3173)
d94f44c 
The Secure audit PR (#3159) added +attributes to source blocks
that contain shell variables ${USER_ROLES} and ${OPERATOR_NAMESPACE}.
Asciidoctor tried to resolve these as AsciiDoc attributes, causing
"missing attribute" warnings that fail the publication builder.

Escape with backslash so Asciidoctor renders them literally while
still resolving {orch-cli} and {prod-operator}.

Co-authored-by: Cursor <cursoragent@cursor.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ibuziuk ibuziuk ibuziuk approved these changes
@tolusha tolusha tolusha approved these changes
@deerskindoll deerskindoll Awaiting requested review from deerskindoll deerskindoll is a code owner
@mkuznyetsov mkuznyetsov Awaiting requested review from mkuznyetsov mkuznyetsov is a code owner
@azatsarynnyy azatsarynnyy Awaiting requested review from azatsarynnyy azatsarynnyy is a code owner automatically assigned from eclipse-che/ecd-che-docs-reviewers

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@gtrivedi88 @ibuziuk @tolusha